Rate Limiting

Rate limit how many HTTP requests can be made in a given period of seconds, minutes, hours, days, months, or years. If the underlying Gateway Service or Route has no authentication layer, the client IP address is used for identifying clients. Otherwise, the Consumer is used if an authentication plugin has been configured.

The advanced version of this plugin, Rate Limiting Advanced, provides the ability to apply multiple limits in sliding or fixed windows, and includes Redis Sentinel and Redis Cluster support.

Kong also provides multiple specialized rate limiting plugins, including rate limiting across LLMs and GraphQL queries. See Rate Limiting in Kong Gateway to choose the plugin that is most useful in your use case.

The Rate Limiting plugin supports three rate limiting strategies: local, cluster, and redis.

This is controlled by the config.policy parameter.

[1]: Only when config.sync_rate option is set to 0 (synchronous behavior).

Two common use cases for rate limiting are:

1. Every transaction counts: The highest level of accuracy is needed. An example is a transaction with financial consequences.
2. Backend protection: Accuracy is not as relevant. The requirement is only to protect backend services from overloading that’s caused either by specific users or by attacks.

Every transaction counts

In this scenario, because accuracy is important, the local policy is not an option. Consider the support effort you might need for Redis, and then choose either cluster or redis.

You could start with the cluster policy, and move to redis if performance reduces drastically.

If using a very high sync frequency, use redis. Very high sync frequencies with cluster mode are not scalable and not recommended. The sync frequency becomes higher when the sync_rate setting is a lower number - for example, a sync_rate of 0.1 is a much higher sync frequency (10 counter syncs per second) than a sync_rate of 1 (1 counter sync per second).

You can calculate what is considered a very high sync rate in your environment based on your topology, number of plugins, their sync rates, and tolerance for loose rate limits.

If you choose to switch strategies, note that you can’t port the existing usage metrics from the Kong Gateway data store to Redis. This might not be a problem with short-lived metrics (for example, seconds or minutes) but if you use metrics with a longer time frame (for example, months), plan your switch carefully.

Backend protection

If accuracy is less important, choose the local policy. You might need to experiment a little before you get a setting that works for your scenario. As the cluster scales to more nodes, more user requests are handled. When the cluster scales down, the probability of false negatives increases. Make sure to adjust your rate limits when scaling.

For example, if a user can make 100 requests every second, and you have an equally balanced 5-node Kong Gateway cluster, you can set the local limit to 30 requests every second. If you see too many false negatives, increase the limit.

To minimize inaccuracies, consider using a consistent-hashing load balancer in front of Kong Gateway. The load balancer ensures that a user is always directed to the same Kong Gateway node, which reduces inaccuracies and prevents scaling problems.

Using cloud authentication with Redis v3.13+

If your plugin uses a Redis datastore, you can authenticate to it with a cloud Redis provider, or with an OAuth 2.0 token endpoint. This allows you to seamlessly rotate credentials without relying on static passwords.

The following providers are supported:

• AWS ElastiCache
• Azure Managed Redis
• Google Cloud Memorystore (with or without Valkey)
• OAuth 2.0 v3.16+, using the client_credentials or password grant type

config:
  policy: redis
  redis:
    host: $INSTANCE_ADDRESS
    username: $INSTANCE_USERNAME
    port: 6379
    cloud_authentication:
      auth_provider: aws
      aws_cache_name: $AWS_CACHE_NAME
      aws_is_serverless: false
      aws_region: $AWS_REGION
      aws_access_key_id: $AWS_ACCESS_KEY_ID
      aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

config:
  policy: redis
  redis:
    host: $INSTANCE_ADDRESS
    username: $INSTANCE_USERNAME
    port: 10000
    cloud_authentication:
      auth_provider: azure
      azure_client_id: $AZURE_CLIENT_ID
      azure_client_secret: $AZURE_CLIENT_SECRET
      azure_tenant_id: $AZURE_TENANT_ID

config:
  policy: redis
  redis:
    host: $INSTANCE_ADDRESS
    port: 6379
    cloud_authentication:
      auth_provider: gcp
      gcp_service_account_json: $GCP_SERVICE_ACCOUNT

config:
  policy: redis
  redis:
    host: $INSTANCE_ADDRESS
    port: 6379
    cloud_authentication:
      auth_provider: oauth
      oauth:
        token_endpoint: $OAUTH_TOKEN_ENDPOINT
        grant_type: client_credentials
        client_id: $OAUTH_CLIENT_ID
        client_secret: $OAUTH_CLIENT_SECRET

If limiting by IP address, it’s important to understand how Kong Gateway determines the IP address of an incoming request.

The IP address is extracted from the request headers sent to Kong Gateway by downstream clients. Typically, these headers are named X-Real-IP or X-Forwarded-For.

By default, Kong Gateway uses the header name X-Real-IP to identify the client’s IP address. If your environment requires a different header, you can specify this by setting the real_ip_header Nginx property. Depending on your network setup, you may also need to configure the trusted_ips Nginx property to include the load balancer IP address. This ensures that Kong Gateway correctly interprets the client’s IP address, even when the request passes through multiple network layers.

When this plugin is enabled, Kong Gateway sends some additional headers back to the client, indicating the state of the rate limiting policies in place:

You can optionally hide the limit and remaining headers with the config.hide_client_headers option.

If more than one limit is set, the plugin returns multiple time limit headers. For example:

X-RateLimit-Limit-Second: 5
X-RateLimit-Remaining-Second: 4
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9

If any of the limits are reached, the plugin returns an HTTP/1.1 429 status code to the client with the following JSON body:

{ "message": "API rate limit exceeded" }

The headers RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset are based on the Internet-Draft RateLimit Header Fields for HTTP and may change in the future to respect specification updates.

Set limit_by to principal to rate limit based on the authenticated Kong Identity Principal instead of the Consumer, credential, IP address, or other supported identifiers.

config:
  limit_by: principal
  second: 10

principal requires an auth plugin that populates the Principal, such as Key Auth configured for Kong Identity Principal authentication.

custom_key overrides the computed rate limiting key with a literal string, regardless of limit_by. This is most useful in combination with expressible config fields, where custom_key’s value comes from a CEL expression instead of a fixed string.

custom_key and each of second, minute, hour, day, month, and year are expressible config fields: instead of always using the static value in config, Kong Gateway can compute the field’s value per request from a CEL expression, for example, reading an attribute of the authenticated Consumer or Principal. If the expression is unset, invalid, or fails to evaluate, Kong Gateway falls back to the field’s static value in config.

For example, you can set custom_key and second as expressions with a static fallback:

config:
  limit_by: principal
  custom_key: unknown-partner    # static fallback
  second: 10                     # static fallback
expressions:
  custom_key: principal.metadata.partner_id
  second: principal.metadata.rate_limit

See also:

• For an example plugin configuration, see Rate limit by Principal metadata.
• For general information on expressible config fields, including limitations, see Dynamic plugin config with CEL.